Let me begin by paying all due respects to Gregg Harris, the author of C64 Forth for the Commodore 64, from whence these string words came (with a few exceptions). I have to compliment Gregg on the thought that went into providing a full range of useful string operators and coming up with a simple length checking scheme. i haven't actually asked Gregg if it's ok to use these, but we know each other, and I doubt anybody is going to try and make their fortune of this string package!
Now that that's out of the way, on to the documentation. The thing that makes string happen in MacForth is the word ". " rather inefficiently takes up dictionary space with the string you specify, and leaves the string's address on the stack. When the stack notation says '$addr', it usually refers either to the address left by " or that left by the actual name of a string - which brings us to $CONSTANT and $VARIABLE.
$CONSTANT - This is the same as $VARIABLE, except it allows you to predefine the string. For example, you would usually say:
" This is a string." $CONSTANT MYSTRING
This would create a string called MYSTRING, and set the maximum byte count to the length of the string, in this case 17.
NOTE: Once the max byte count is set, the string can NEVER be longer, and all string operations will clip to the max byte count (let's call it max cnt).
Once the string is created, it can be changed just like a string created with $VARIABLE (see below).
$VARIABLE - This is used to create a nondefined string entry like so:
10 $VARIABLE MESSAGE
This creates the null string MESSAGE with a max cnt of 10. The biggest max cnt you can have is 255. When MESSAGE is later executed (or MYSTRING created with $CONSTANT), the address returned is one past the max cnt, which is the current string length byte, followed by the actual string itself, in standard Forth string format.
$! - This is the string equivalent of ! (store), but it works with two string addresses, transferring the contents (but not the max cnt) of $FROM to $TO (refer to stack notation).
Examples: " Howdy! " MESSAGE $!
MESSAGE MYSTRING $!
MYSTRING would now be "Howdy! ". If you see something like this:
7 $VARIABLE SMALL
" This is way too big" SMALL $!
SMALL $. This is ok
remember that SMALL is limited to 10 characters! (Don't go hacking away trying to find out what went wrong!).
$TOPAD - Used internally, just moves a string to the PAD for processing.
$+ - This concatenates 2 strings, leaving the result at PAD for further processing or storage. So the lines
20 $VARIABLE WHOLESTRING
" Half of " $CONSTANT 1STHALF
" a string" $CONSTANT 2NDHALF
1STHALF 2NDHALF $+ WHOLESTRING $!
would leave WHOLESTRING as "Half of a string". You could also do
6 $VARIABLE N1
" 123" N1 $!
N1 " 456" $+ N1 $!
with N1 being "123456".
RIGHT$ - Leaves the rightmost n characters of the string at $addr. If n is greater than the current string length, RIGHT$ just leaves $addr (the whole string).
Example: N1 3 RIGHT$ $. 456 ok
LEFT$ - Leaves the leftmost n characters of the string at $addr. If you use negative n, it will be interpreted as an unsigned integer.
Example: N1 3 LEFT$ $. 123 ok
$. - This prints the string at $addr. If the string is null, $. prints nothing.
MID$ - Leaves the substring of the string at $addr beginning at startpos and continuing for #chr characters (or until the end of the string is reached). If startpos is greater than the current string length, the result is a null string.
Example: N1 3 2 MID$ $. 34 ok
LEN - Simply leaves the current length of the string at $addr on the stack.
Example: N1 LEN . 6 ok
ASC - Leaves the ASCII value of the first character of the string at $addr on the stack.
Example: HEX N1 ASC . 31 ok
NUL$ - I added this as a convenient way to null a string (because you can't create one using ").
Example: MESSAGE NUL$ MESSAGE $. ok
CHR$ - Creates a one character string from the (ASCII) value on the stack.
Example: HEX 31 CHR$ $. 1 ok
$COMPARE - This neat little operator compares two strings and leaves a positive, a negative, or a zero flag, depending on the following conditions:
positive flag: $1 is either longer than $2 or has a greater ASCII value
negative flag: $1 is either shorter than $2 or has a smaller ASCII value
zero flag: $1 and $2 are the same
Examples: " 123" $CONSTANT S1
" 1234" $CONSTANT S2
" ABC" $CONSTANT S3
S1 S2 $COMPARE . -1 ok
S3 S1 $COMPARE . 1 ok
S2 S1 $COMPARE . 1 ok
S2 S3 $COMPARE . -1 ok
S1 S1 $COMPARE . 0 ok
VAL - Converts the string at $addr to a number on the stack. If the string is not a valid number, you will get an error.
Example: S1 VAL . 123 ok
$< $= $> - These compare two strings (using $COMPARE) and leave a boolean flag as a result.
Example: S1 $< S2 IFTRUE ." YUP" IFEND YUP ok
STR$ - Converts the number on the stack to a string. If the number is negative, there is a leading minus sign, otherwise there is a leading space.
Example: 1001 STR$ $. 1001 ok
-1001 STR$ $. -1001 ok
POS$ - Tries to find substring$ within dest$. If it succeeds, it leaves the position within the string (1 being the first character), otherwise leaves 0.
Example: " songbirds" $CONSTANT BIRDS
" song" BIRDS POS$ . 1 ok
" birds" BIRDS POS$ . 5 ok
" huh?" BIRDS POS$ . 0 ok
INPUT$ - Since MacForth doesn't have a max cnt byte in its strings, this was necessary (and more convenient) to maintain range-checking. It allows you to input up to 255 characters, and clips the input string to the max cnt of the string you specify by $addr.
Example: 4 $VARIABLE STRING
STRING INPUT$ This string is way too long to fit - isn't it?
STRING $. This ok
NOTE: If you want to use the range limiting of MacForth's INPUT.STRING (which INPUT$ uses), the string will be stored ok, but MAKE SURE the input limit is less than the max cnt of the destination string!
* * * * * * * * * * * * * * * * * * * *
That's all folks! I hope you find these little babies useful. Don't hesitate to think up new ones; if you do, make sure you leave string results on the PAD, and that you always clip to max cnt. Have fun!
